<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
        "http://www.w3.org/TR/html4/strict.dtd">
<HTML><HEAD><TITLE>nibbles</TITLE><LINK TYPE="text/css" TITLE="default" REL="stylesheet" MEDIA="screen" HREF="style.css" /></HEAD><BODY><H1>nibbles</H1><P>nibbles is a library for accessing multibyte integers from
octet arrays and streams.  While such accessors are straightforward to
write, nibbles aims to centralize such facilities and also
provide optimizations for them when appropriate.</P><H2>Installation</H2><P>nibbles can be downloaded at <A HREF="http://www.method-combination.net/lisp/files/nibbles.tar.gz">http://www.method-combination.net/lisp/files/nibbles.tar.gz</A>.  The latest version is 0.11.</P><P>It comes with an ASDF system definition, so <TT>(ASDF:OOS
'ASDF:LOAD-OP :NIBBLES)</TT> should be all that you need to get started.</P><H2>License</H2><P>nibbles is released under a MIT-like license; you can do pretty
much anything you want to with the code except claim that you wrote
it.</P><H2>Integer array accessors</H2><DIV CLASS="lisp-symbol"><A NAME="ub16ref/le"></A><TT><STRONG>ub16ref/le</STRONG> <EM>vector</EM> <EM>index</EM> =&gt; <EM>value</EM></TT><BR /><A NAME="ub32ref/le"></A><TT><STRONG>ub32ref/le</STRONG> <EM>vector</EM> <EM>index</EM> =&gt; <EM>value</EM></TT><BR /><A NAME="ub64ref/le"></A><TT><STRONG>ub64ref/le</STRONG> <EM>vector</EM> <EM>index</EM> =&gt; <EM>value</EM></TT><BR /></DIV><P>This family of functions accesses an unsigned 16-bit, 32-bit or
64-bit value stored in little-endian order starting at <EM>index</EM> in <EM>vector</EM>.  <EM>vector</EM> must be a <TT>(VECTOR (UNSIGNED-BYTE 8))</TT>. These functions are SETFable.  For instance:</P><PRE>CL-USER> (nibbles:ub16ref/le (coerce #(42 53) '(vector (unsigned-byte 8))) 0)
13610
CL-USER> (format nil "~X" *)
"352A"</PRE><DIV CLASS="lisp-symbol"><A NAME="ub16ref/be"></A><TT><STRONG>ub16ref/be</STRONG> <EM>vector</EM> <EM>index</EM> =&gt; <EM>value</EM></TT><BR /><A NAME="ub32ref/be"></A><TT><STRONG>ub32ref/be</STRONG> <EM>vector</EM> <EM>index</EM> =&gt; <EM>value</EM></TT><BR /><A NAME="ub64ref/be"></A><TT><STRONG>ub64ref/be</STRONG> <EM>vector</EM> <EM>index</EM> =&gt; <EM>value</EM></TT><BR /></DIV><P>As the above, only the value is accessed in big-endian order.  For instance:</P><PRE>CL-USER> (nibbles:ub16ref/be (coerce #(42 53) '(vector (unsigned-byte 8))) 0)
10805
CL-USER> (format nil "~X" *)
"2A35"</PRE><DIV CLASS="lisp-symbol"><A NAME="sb16ref/le"></A><TT><STRONG>sb16ref/le</STRONG> <EM>vector</EM> <EM>index</EM> =&gt; <EM>value</EM></TT><BR /><A NAME="sb32ref/le"></A><TT><STRONG>sb32ref/le</STRONG> <EM>vector</EM> <EM>index</EM> =&gt; <EM>value</EM></TT><BR /><A NAME="sb64ref/le"></A><TT><STRONG>sb64ref/le</STRONG> <EM>vector</EM> <EM>index</EM> =&gt; <EM>value</EM></TT><BR /></DIV><DIV CLASS="lisp-symbol"><A NAME="sb16ref/be"></A><TT><STRONG>sb16ref/be</STRONG> <EM>vector</EM> <EM>index</EM> =&gt; <EM>value</EM></TT><BR /><A NAME="sb32ref/be"></A><TT><STRONG>sb32ref/be</STRONG> <EM>vector</EM> <EM>index</EM> =&gt; <EM>value</EM></TT><BR /><A NAME="sb64ref/be"></A><TT><STRONG>sb64ref/be</STRONG> <EM>vector</EM> <EM>index</EM> =&gt; <EM>value</EM></TT><BR /></DIV><P>As the above, only the value accessed is a signed value.  For instance:</P><PRE>CL-USER> (nibbles:sb16ref/be (coerce #(81 92) '(vector (unsigned-byte 8))) 0)
20828
CL-USER> (nibbles:sb16ref/be (coerce #(129 135) '(vector (unsigned-byte 8))) 0)
-32377
CL-USER> (format nil "~X ~X" ** *)
"515C -7E79"
CL-USER> (nibbles:sb16ref/le (coerce #(81 92) '(vector (unsigned-byte 8))) 0)
23633
CL-USER> (nibbles:sb16ref/le (coerce #(129 135) '(vector (unsigned-byte 8))) 0)
-30847
CL-USER> (format nil "~X ~X" ** *)
"5C51 -787F"</PRE><H2>Stream readers</H2><DIV CLASS="lisp-symbol"><A NAME="read-ub16/le"></A><TT><STRONG>read-ub16/le</STRONG> <EM>stream</EM> =&gt; <EM>value</EM></TT><BR /><A NAME="read-ub32/le"></A><TT><STRONG>read-ub32/le</STRONG> <EM>stream</EM> =&gt; <EM>value</EM></TT><BR /><A NAME="read-ub64/le"></A><TT><STRONG>read-ub64/le</STRONG> <EM>stream</EM> =&gt; <EM>value</EM></TT><BR /></DIV><P>This family of functions reads an unsigned 16-bit, 32-bit, or
64-bit value from <EM>stream</EM> in little-endian order.  <EM>stream</EM>
must have an element-type of <TT>(UNSIGNED-BYTE 8)</TT>.</P><DIV CLASS="lisp-symbol"><A NAME="read-ub16/be"></A><TT><STRONG>read-ub16/be</STRONG> <EM>stream</EM> =&gt; <EM>value</EM></TT><BR /><A NAME="read-ub32/be"></A><TT><STRONG>read-ub32/be</STRONG> <EM>stream</EM> =&gt; <EM>value</EM></TT><BR /><A NAME="read-ub64/be"></A><TT><STRONG>read-ub64/be</STRONG> <EM>stream</EM> =&gt; <EM>value</EM></TT><BR /></DIV><P>As the above, only the value is read in big-endian order.</P><DIV CLASS="lisp-symbol"><A NAME="read-sb16/le"></A><TT><STRONG>read-sb16/le</STRONG> <EM>stream</EM> =&gt; <EM>value</EM></TT><BR /><A NAME="read-sb32/le"></A><TT><STRONG>read-sb32/le</STRONG> <EM>stream</EM> =&gt; <EM>value</EM></TT><BR /><A NAME="read-sb64/le"></A><TT><STRONG>read-sb64/le</STRONG> <EM>stream</EM> =&gt; <EM>value</EM></TT><BR /></DIV><DIV CLASS="lisp-symbol"><A NAME="read-sb16/be"></A><TT><STRONG>read-sb16/be</STRONG> <EM>stream</EM> =&gt; <EM>value</EM></TT><BR /><A NAME="read-sb32/be"></A><TT><STRONG>read-sb32/be</STRONG> <EM>stream</EM> =&gt; <EM>value</EM></TT><BR /><A NAME="read-sb64/be"></A><TT><STRONG>read-sb64/be</STRONG> <EM>stream</EM> =&gt; <EM>value</EM></TT><BR /></DIV><P>As the above, only the value is signed, rather than unsigned.</P><H2>Stream writers</H2><DIV CLASS="lisp-symbol"><A NAME="write-ub16/le"></A><TT><STRONG>write-ub16/le</STRONG> <EM>integer</EM> <EM>stream</EM> =&gt; <EM>value</EM></TT><BR /><A NAME="write-ub32/le"></A><TT><STRONG>write-ub32/le</STRONG> <EM>integer</EM> <EM>stream</EM> =&gt; <EM>value</EM></TT><BR /><A NAME="write-ub64/le"></A><TT><STRONG>write-ub64/le</STRONG> <EM>integer</EM> <EM>stream</EM> =&gt; <EM>value</EM></TT><BR /></DIV><P>This family of functions writes an unsigned 16-bit, 32-bit, or
64-bit <EM>integer</EM> to <EM>stream</EM> in little-endian order.  <EM>stream</EM>
must have an element-type of <TT>(UNSIGNED-BYTE 8)</TT>.  The value written
is returned.</P><DIV CLASS="lisp-symbol"><A NAME="write-ub16/be"></A><TT><STRONG>write-ub16/be</STRONG> <EM>integer</EM> <EM>stream</EM> =&gt; <EM>value</EM></TT><BR /><A NAME="write-ub32/be"></A><TT><STRONG>write-ub32/be</STRONG> <EM>integer</EM> <EM>stream</EM> =&gt; <EM>value</EM></TT><BR /><A NAME="write-ub64/be"></A><TT><STRONG>write-ub64/be</STRONG> <EM>integer</EM> <EM>stream</EM> =&gt; <EM>value</EM></TT><BR /></DIV><P>As the above, only the value is read in big-endian order.</P><DIV CLASS="lisp-symbol"><A NAME="write-sb16/le"></A><TT><STRONG>write-sb16/le</STRONG> <EM>integer</EM> <EM>stream</EM> =&gt; <EM>value</EM></TT><BR /><A NAME="write-sb32/le"></A><TT><STRONG>write-sb32/le</STRONG> <EM>integer</EM> <EM>stream</EM> =&gt; <EM>value</EM></TT><BR /><A NAME="write-sb64/le"></A><TT><STRONG>write-sb64/le</STRONG> <EM>integer</EM> <EM>stream</EM> =&gt; <EM>value</EM></TT><BR /></DIV><DIV CLASS="lisp-symbol"><A NAME="write-sb16/be"></A><TT><STRONG>write-sb16/be</STRONG> <EM>integer</EM> <EM>stream</EM> =&gt; <EM>value</EM></TT><BR /><A NAME="write-sb32/be"></A><TT><STRONG>write-sb32/be</STRONG> <EM>integer</EM> <EM>stream</EM> =&gt; <EM>value</EM></TT><BR /><A NAME="write-sb64/be"></A><TT><STRONG>write-sb64/be</STRONG> <EM>integer</EM> <EM>stream</EM> =&gt; <EM>value</EM></TT><BR /></DIV><P>As the above, only the value is signed, rather than unsigned.</P></BODY></HTML>